\name{StackedDots}
\alias{StackedDots}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Stacked Dot Plot}
\description{
This function creates a stacked dot plot.  This type of plot is nice to present the distribution of smaller datasets because the plot stays closer to the actual data than typical histograms or kernel density plots.
}
\usage{
StackedDots(data, map = link(), FUN = median, symm = FALSE,
  plot = TRUE, ...)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{data}{\code{data} typically a data frame (or list) containing all the data.  It is possible to pass a vector directly, but then \code{map} _must be missing_.  Hopefully this will be fixed in a future release.
}
  \item{map}{\code{map} this is a call to \code{link} to map specific variables within \code{data} to different aspects of the graph.  Right now, the only options are \code{x}, the actual variable to plot and \code{color} which can be another variable the same length as \code{x} specifying colors for each point (e.g., a factor) or a single character string giving the color for all points (e.g., "blue").  It is also possible to override the default \code{h} value and set the desired point diameter directly.
}
  \item{FUN}{\code{FUN} this sets the function used to center each stack.  The default is \code{median}, another reasonable choice would be \code{mean}.
}
  \item{symm}{Logical, specifying whether to create an assymetric or symmetric plot. The default is \code{symm = FALSE} (assymetric, like a histogram).
}
  \item{plot}{Logical indicating whether or not to create a plot.  Defaults to \code{plot = TRUE}.
}
  \item{\dots}{\code{\dots} additional arguments to be passed to the plot (if plotting) such as axis labels or a title.
}
}
\details{
Reading the documentation for \code{StackAlgorithm} and \code{link} will clarify _how_ this function works further.  \code{StackedDots} serves as somoething of a wrapper to bring everything else together and handle a few loose ends.  Also, the actual plotting is handled by special plot methods fot DotStack objects.
}
\value{
  A formal S4 DotStack object.  Optionally has the side effect of creating a plot.
  \item{@original}{S4 slot containing the original data to be plotted.}
  \item{@name}{S4 slot containing the variable name of the original data.}
  \item{@x}{S4 slot containing the x axis coordinates of the data (for each stack).}
  \item{@y}{S4 slot containing the y axis coordinates of each data point.}
  \item{@color}{S4 slot containing the color to be used for each point.}
  \item{@shape}{Currently not used.}
  \item{@key}{S4 slot containing a "key" to map the coordinates etc. to the original data.}
  \item{@ok}{S4 slot containing which values of the original data are non-missing.}
  \item{@h}{S4 slot containing the \code{h} parameter specifying the radii of the dots.}
}
\references{
  Tuan Nhon Dang, Leland Wilkinson, & Anushka Anand. Stacking Graphic Elements to Avoid Over-Plotting. (2010). \emph{IEEE TRANSACTIONS ON VISUALIZATION AND COMPUTER GRAPHICS}, 16:6, 1044--1052.

  Leland Wilkinson. (1999). Dot Plots. \emph{The American Statistician}, 53:3, 276--281.
}
\author{Joshua Wiley, \url{http://joshuawiley.com/}}
\note{Hopefully I will expand the notes and details soon.}

\seealso{\code{\link{StackAlgorithm}} and \code{\link{link}}}
\examples{
## Data
dat <- data.frame(x = c(1:5, 11:13))

## Create a simple assymetric plot using all defaults
test <- StackedDots(data = dat, map = link(x = x))

## the structure of the DotStack object
str(test)

## print and show methods and indexing methods
test
print(test)
test[]

## Another plot this time customizing the color and dot diameter
StackedDots(data = dat, map = link(x = x, h = .5, color = "blue"))

## A symmetrical plot
StackedDots(data = dat, map = link(x = x), symm = TRUE)

## Using a larger dataset
data(webstats)

## This distribution looks slightly skewed and also quite variables
StackedDots(data = webstats, map = link(x = Hits, h = 1.5))
## We can try a square root transformation
StackedDots(data = webstats, map = link(x = sqrt(Hits)))
## a log transformation seems a little too extreme
StackedDots(data = webstats, map = link(x = log(Hits), h = .02))

## Another Plot
StackedDots(data = webstats, map = link(x = sqrt(Visits), h = .035))

rm(dat, test, webstats)
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{hplot}
